\input macros
\drafttrue
\def\bookline{\CLOS\  Specification}
\def\chapline{Functions in the Meta-Object Protocol}

\beginChapter 3.{Common Lisp Object System Specification}%
{Functions in the Meta-Object Protocol}{Functions in the Meta-Object Protocol}

This document was written by Daniel G. Bobrow, Linda G. DeMichiel,\break
Richard P. Gabriel, Sonya E. Keene, Gregor Kiczales, and David A. Moon.

Contributors to this document include Patrick Dussud, Kenneth Kahn,\break
Jim Kempf, Larry Masinter, Mark Stefik,
Daniel L. Weinreb, and Jon L White.

\endTitlePage

\beginSection{Introduction}

This chapter describes some of the functions provided by the \CLOS\
Meta-Object Protocol.  This document is preliminary; it is not to
be construed as presenting a complete description of Meta-Object
Protocol.

The description of each function includes its purpose, its syntax, the
semantics of its arguments and returned values, and often an example
and cross-references to related functions.  This chapter is reference
material that requires an understanding of the basic concepts of the 
Common Lisp Object System.  The functions are arranged in alphabetic 
order for convenient reference.  

\endSection%{Introduction}

\begincom{allocate-instance}\ftype{Generic Function}

\label Purpose:

The generic function {\bf allocate-instance} allocates storage for an instance
of the given class.

\label Syntax:

\Defgen {allocate-instance} {class\/ {\key \&allow-other-keys}}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The result is the newly-allocated instance.

\label Remarks:

The keyword name of each keyword parameter specifier in the lambda-list
of any method defined for {\bf allocate-instance} becomes an initialization
argument for all classes for which that method is applicable.

Programmers can customize the behavior of {\bf allocate-instance} by
defining additional methods for it or replacing the system-supplied
default method.


\label See Also:

``Object Creation and Initialization''

\endcom


\begincom{check-initargs}\ftype{Generic Function}

\label Purpose:

The generic function {\bf check-initargs} is called by {\bf make-instance}
to test the validity of initialization arguments.

The system-supplied default method implements the rules for validity 
described in the section ``Object Creation and Initialization.''

%The result is an initialization argument list.

\label Syntax:

\Defgen {check-initargs} {class initarg-list}

\label Arguments:

The {\it class\/} argument is a class object.

The {\it initarg-list\/} argument is an initialization argument list.

\label Values:

The value returned by {\bf check-initargs} is ignored by {\bf make-instance}.

\label Remarks:

Programmers can customize the behavior of {\bf check-initargs} by
defining additional methods for it or by replacing the system-supplied
default method.

\label See Also:

``Object Creation and Initialization''

\endcom


\begincom{class-all-initargs}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-all-initargs} returns a list of the names of
all initialization arguments that apply to a given class, including
the names of inherited initialization arguments.

This result is the union of the following two sets of the initialization
argument names: the initialization argument names contained in the result
of {\tt (class-all-slot-initargs {\it class\/})} and the initialization
argument names that are defined by all the applicable methods for
{\bf allocate-instance} and {\bf initialize-instance}.

\label Syntax:

\Defgen {class-all-initargs} {class}

\label Arguments:

The {\it class\/} argument is a class object.


\label Values:

The result is a list of the names of all initargs that apply to a
given class, including the names of inherited initargs.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

\label See Also:

``Object Creation and Initialization''

{\bf make-instance

initialize-instance}

\endcom


\begincom{class-all-initarg-defaults}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-all-initarg-defaults} returns a list,
each of whose elements is a list consisting of the name of an
initialization argument defined for a slot in that class or any of its
superclasses followed by the default value function and the default
value form for that initialization argument.  The default value
function is the function whose body is the default value form; this
function is created in the lexical environment of the {\bf defclass}
form that contains the default value form.

\label Syntax:

\Defgen {class-all-initarg-defaults} {class}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The result is a list of the form {\tt (({\it initialization-argument-name default-value-function default-value-form\/}) $\ldots$ )}.

The default value form is the form
that was originally specified.  It is retained only for documentation.
It is not legitimate to attempt to evaluate default value form.

The default value function is what actually gets called; its effect is
equivalent to enclosing the default value form in the appropriate lexical
environment.  The default value function takes no arguments.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

%\label See Also:

\endcom


\begincom{class-all-slot-initargs}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-all-slot-initargs} returns a list,
each of whose elements is a list consisting of the name of an
initialization argument defined for a slot in that class or any of its
superclasses followed by the names of all slots defined in the {\bf
defclass} forms for that class or any of its superclasses for which
that initialization argument is defined.

\label Syntax:

\Defgen {class-all-slot-initargs} {class}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The result is a list of the form {\tt (({\it
initialization-argument-name slot-name} $\ldots$) $\ldots$ )}.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

%\label See Also:

\endcom


\begincom{class-direct-initargs}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-direct-initargs} returns a list of the names
of all initialization arguments corresponding to a given class.  These
initialization arguments include those that were specified using the
{\bf :initarg} slot option in the {\bf defclass form} for the given
class, as well as those that were defined in the lambda-lists for methods on
{\bf allocate-instance} and {\bf initialize-instance} that are defined for
the exact given class.

\label Syntax:

\Defgen {class-direct-initargs} {class}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The result is a list of initialization argument names.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

\label See Also:

``Object Creation and Initialization''

{\bf make-instance

allocate-instance

initialize-instance}

\endcom


\begincom{class-direct-initarg-defaults}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-direct-initarg-defaults} returns a list,
each of whose elements is a list consisting of the name of an
initialization argument defined for a slot in that exact class followed by
the default value function and the default value form for that initialization
argument.  The default value function is the function whose body is the
default value form; this function is created in the lexical environment of
the {\bf defclass} form that contains the default value form.

\label Syntax:

\Defgen {class-direct-initarg-defaults} {class}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The result is a list of the form {\tt (({\it initialization-argument-name default-value-function default-value-form\/}) $\ldots$ )}.

The default value form is the form
that was originally specified.  It is retained only for documentation.
It is not legitimate to attempt to evaluate default value form.

The default value function is what actually gets called; its effect is
equivalent to enclosing the default value form in the appropriate lexical
environment.  The default value function takes no arguments.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

%\label See Also:

\endcom



\begincom{class-direct-slot-initargs}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-direct-slot-initargs} returns a list,
each of whose elements is a list consisting of the name of an
initialization argument defined for a slot in that exact class followed by
the names of all slots defined in the {\bf defclass} form for that
class for which that initialization argument is defined.

\label Syntax:

\Defgen {class-direct-slot-initargs} {class}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The result is a list of the form {\tt (({\it
initialization-argument-name slot-name} $\ldots$) $\ldots$ )}.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

%\label See Also:

\endcom


\begincom{compute-applicable-methods}\ftype{Generic Function}

\label Purpose:

The generic function {\bf compute-applicable-methods} returns a list
of the methods of the generic function that are applicable for the
given arguments.

\label Syntax:

\Defgen {compute-applicable-methods} {generic-function argument-list}

\label Arguments:

The {\it generic-function\/} argument is a generic function object.

The {\it argument-list\/} argument is the argument list for that
generic function for which the applicable methods are to be
determined.

\label Values:

The result is a list of method objects.

\label Remarks:

The results are undefined if the value returned by this function is
modified.

It is permitted, but not required, for an implementation to return values
that share with internal data structures.

%\label See Also:

\endcom



\begincom{default-initargs}\ftype{Generic Function}

\label Purpose:

The system-supplied method for {\bf default-initargs} implements the
{\bf :default-initargs} class option by appending initialization arguments
that do not appear in the {\it initarg-list\/} argument to the
{\it initarg-list\/} argument and returning the result.

The order of the initialization arguments appended to the list is determined
by the rules for duplicate initialization arguments presented in the
section ``Rules for Duplication of Initialization Arguments.''

The {\it initarg-list\/} argument is not modified.

\label Syntax:

\Defgen {default-initargs} {class initarg-list}

\label Arguments:

The {\it class\/} argument is a class object.

The {\it initarg-list\/} argument is an initialization
argument list.

\label Values:

The result is an initialization argument list.

\label Remarks:

Programmers can customize the behavior of {\bf default-initargs} by
defining additional methods for it or replacing the system-supplied
default method.

\label See Also:

``Object Creation and Initialization''

``Rules for Duplication of Initialization Arguments''

\endcom


\begincom{finalize-inheritance}\ftype{Generic Function}

\label Purpose:

The generic function {\bf finalize-inheritance} is called at least once
before a class is instantiated and is called again whenever the class
or any of its superclasses is redefined in any way or whenever an
initialization method is defined, redefined, or undefined.

The generic function {\bf finalize-inheritance} is not intended to be called
by programmers.  Programmers are expected to write methods for it.

\label Syntax:

\Defgen {finalize-inheritance} {class\/ {\key :slots :methods :initargs}}

\label Arguments:

The {\it class\/} argument is a class object.

The {\bf :slots}, {\bf :methods}, and {\bf :initargs} arguments are
boolean values that are true when the specified type of inheritance
needs to be recomputed.

\label Values:

The value returned by {\bf finalize-inheritance} is ignored.

\label Remarks:

The system-supplied methods for {\bf finalize-inheritance} conspire
with methods for {\bf make-instance}, {\bf default-initargs}, {\bf
check-initargs}, {\bf allocate-instance}, and {\bf
initialize-instance} to speed up object creation by precomputing
information and storing it in slots of the class.  This optimization
is implementation dependent, but the {\bf finalize-inheritance}
mechanism that makes such optimizations possible is standardized.

Users with special optimization needs can write methods for {\bf
finalize-inheritance} to precompute information based on inherited
information and to update the precomputed information whenever
changes occur.

\label See Also:

{\bf make-instance

check-initargs}

\endcom


\begincom{method-keyword-names}\ftype{Generic Function}

\label Purpose:

The generic function {\bf method-keyword-names} returns a list of symbols
indicating the keyword names of the keyword parameter specifiers in
the given method's lambda-list.  The result is the symbol {\bf
\&allow-other-keys} instead of a list if the method's lambda-list
contains that symbol.

\label Syntax:

\Defgen {method-keyword-names} {method}

\label Arguments:

The {\it method\/} argument is a method object.

\label Values:

The result is a list of symbols or the symbol {\bf
\&allow-other-keys}.

%\label Remarks:

%\label See Also:

\endcom


\begincom{slot-boundp-using-class}\ftype{Generic Function}

\label Purpose:

The generic function {\bf slot-boundp-using-class} tests whether a
specific slot in an instance of a given class is bound.

\label Syntax:

\Defgen {slot-boundp-using-class} {class instance slot-name}

\label Arguments:

The arguments are the class of the instance, the instance itself, and
the name of the slot.  The {\it class\/} argument is a class object.

\label Values:

The generic function {\bf slot-boundp-using-class} returns true or false.

\label Remarks:

The set of arguments (including the class of the instance) facilitates
defining methods on the metaclass for {\bf slot-boundp-using-class}.

The generic function {\bf slot-boundp-using-class} is intended for use
by {\bf slot-boundp}.

\label See Also:

{\bf slot-boundp}

\endcom


\begincom{slot-makunbound-using-class}\ftype{Generic Function}

\label Purpose:

The generic function {\bf slot-makunbound-using-class} restores a slot
in an instance to the uninitialized state.

\label Syntax:

\Defgen {slot-makunbound-using-class} {class instance slot-name}

\label Arguments:

The arguments are the class of the instance, the instance itself, and
the name of the slot.  The {\it class\/} argument is a class object.

\label Values:

The instance is returned as the result.

\label Remarks:

The set of arguments (including the class of the instance) facilitates
defining methods on the metaclass for {\bf slot-makunbound-using-class}.

The generic function {\bf slot-makunbound-using-class} is intended for use
by {\bf slot-makunbound}.

\label See Also:

{\bf slot-makunbound}

\endcom


\begincom{slot-value-using-class}\ftype{Generic Function}

\label Purpose:

The generic function {\bf slot-value-using-class} returns the value
contained in the slot {\it slot-name\/} of the given object of the
given class.  If there is no slot with that name, an error is
signaled.

The macro {\bf setf} can be used with {\bf slot-value-using-class} to
change the value of a slot.

\label Syntax:

\Defgen {slot-value-using-class} {class object slot-name}

\label Arguments:

The arguments are the class of the object, the object itself, and
the name of the slot.  The {\it class\/} argument is a class object.

\label Values:

The result is the value contained in the given slot.

\label Remarks:

The set of arguments (including the class of the instance) facilitates
defining methods on the metaclass for {\bf slot-value-using-class}.

The generic function {\bf slot-value-using-class} is intended for use
by {\bf slot-value}.

\label See Also:

{\bf slot-value}

\endcom

\endChapter
\bye